<!DOCTYPE html>

<html lang="en" data-content_root="../../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Tutorial structure &#8212; Pytch  documentation</title>
    <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=03e43079" />
    <link rel="stylesheet" type="text/css" href="../../_static/classic.css?v=36340f97" />
    <link rel="stylesheet" type="text/css" href="../../_static/css/pytch-classic.css?v=0321735e" />
    
    <script src="../../_static/documentation_options.js?v=7f41d439"></script>
    <script src="../../_static/doctools.js?v=9bcbadda"></script>
    <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="icon" href="../../_static/favicon.ico"/>
    <link rel="author" title="About these documents" href="../../about.html" />
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="Compiling a tutorial from a Git repository" href="fromgitrepo.html" />
    <link rel="prev" title="Tools for writing a tutorial" href="index.html" /> 
  </head><body>
<div class="NavBar">
  <a href="../../../app/"><h1>Pytch</h1></a>
  <ul>
    <a href="https://pytch.scss.tcd.ie/"><li>About Pytch</li></a>
    <a href="../../index.html"><li>Help</li></a>
    <a href="../../../app/tutorials/"><li>Tutorials</li></a>
    <a href="../../../app/my-projects/"><li>My projects</li></a>
  </ul>
</div>
<div class="warning-work-in-progress">
  <p>These help pages are incomplete — we are working on it!</p>
</div>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="tutorial-structure">
<h1>Tutorial structure<a class="headerlink" href="#tutorial-structure" title="Link to this heading">¶</a></h1>
<p>The <code class="docutils literal notranslate"><span class="pre">{base}</span></code> commit of the tutorial should add the <code class="docutils literal notranslate"><span class="pre">code.py</span></code> file
with the same contents as the IDE starts off with in the code pane.</p>
<section id="structure-on-the-server">
<h2>Structure on the server<a class="headerlink" href="#structure-on-the-server" title="Link to this heading">¶</a></h2>
<p>The URL structure of the tutorials is:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>pytch.org/[beta/1234abcd/]
├── index.html
:
└── tutorials/1234abcd1234abcd1234
     ├── tutorial-index.html
     ├── bunner/
     │   ├── tutorial.html
     │   ├── summary.html
     │   ├── project-assets.json
     │   ├── tutorial-assets/
     │   │   └── summary-screenshot.png
     │   └── project-assets/
     │       └── images/
     │           ├── world.png
     │           ├── car00.png
     :           :   :
     │           └── digit-9.png
     ├── boing/
     │   ├── tutorial.html
     │   ├── summary.html
     │   ├── project-assets.json
     │   ├── tutorial-assets/
     │   │   └── summary-screenshot.png
     │   └── project-assets/
     │       └── images/
     │           ├── robot-normal.png
     │           ├── robot-flash.png
     :           :   :
     │           └── table.png
     :
     etc.
</pre></div>
</div>
<p>(The <code class="docutils literal notranslate"><span class="pre">1234abcd1234abcd1234</span></code> is a shortened SHA1 to avoid false
cacheing of updated tutorial content.)</p>
</section>
<section id="structure-of-html-fragment">
<h2>Structure of HTML fragment<a class="headerlink" href="#structure-of-html-fragment" title="Link to this heading">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">tutorial.html</span></code> file is not a complete HTML page.  It is a
fragment whose top-level element is a <code class="docutils literal notranslate"><span class="pre">&lt;div&gt;</span></code>, which contains the
<em>front-matter</em> and the <em>chapters</em> of the tutorial.</p>
<p>The structure is:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>&lt;div class=&quot;tutorial-bundle&quot; data-tip-sha1=&quot;...SHA1...&quot;&gt;
  &lt;div class=&quot;front-matter&quot;
       data-complete-code-text=&quot;import pytch etc&quot;&gt;
    &lt;h1&gt;Bunner!&lt;/h1&gt;
    &lt;p&gt;In this tutorial etc.&lt;/p&gt;
  &lt;/div&gt;
  &lt;div class=&quot;chapter-content&quot;&gt;  &lt;!-- first chapter --&gt;
    &lt;h2&gt;Making the stage&lt;/h2&gt;
    &lt;p&gt;First we make the stage etc.&lt;/p&gt;
    &lt;div class=&quot;patch-container&quot;
         data-code-as-of-commit=&quot;import pytch etc&quot;&gt;
      &lt;div class=&quot;patch&quot;&gt;
        &lt;table&gt; &lt;!-- rows for lines of first hunk of patch --&gt; &lt;/table&gt;
        &lt;table&gt; &lt;!-- rows for lines of second hunk of patch --&gt; &lt;/table&gt;
      &lt;/div&gt;
    &lt;/div&gt;
    &lt;p&gt;And then we etc.&lt;/p&gt;
    &lt;div class=&quot;patch-container&quot;
         data-code-as-of-commit=&quot;...&quot;&gt;
       &lt;div class=&quot;patch&quot;&gt;
         &lt;!-- &lt;table&gt;s for hunks of patch --&gt;
       &lt;/div&gt;
    &lt;/div&gt;
  &lt;/div&gt;
  &lt;div class=&quot;chapter-content&quot;&gt;  &lt;!-- second chapter --&gt;
    &lt;h2&gt;Adding our hero&lt;/h2&gt;
    &lt;p&gt;Next we bring in the rabbit etc.&lt;/p&gt;
    &lt;!-- more &lt;p&gt;s, patch-&lt;div&gt;s, &lt;h3&gt;s, etc. --&gt;
  &lt;/div&gt;
  &lt;!-- further chapters --&gt;
&lt;/div&gt;
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">&lt;table&gt;</span></code> elements of class <code class="docutils literal notranslate"><span class="pre">patch</span></code> have their bodies grouped
into <code class="docutils literal notranslate"><span class="pre">&lt;tbody&gt;&gt;</span></code> elements, grouping together each kind of hunk line —
<em>add</em>, <em>delete</em>, or <em>unchanged</em>.</p>
<p>An <em>add</em> <code class="docutils literal notranslate"><span class="pre">&lt;tbody&gt;</span></code> has an attribute <code class="docutils literal notranslate"><span class="pre">data-added-text</span></code> whose value
is the text added by that group of lines.  The IDE picks this up to
allow the <em>copy</em> functionality to work.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">data-tip-sha1</span></code> attribute on the top-level <code class="docutils literal notranslate"><span class="pre">div</span></code> notes which
commit the tutorial was generated from.  Currently it’s not used but
might one day be part of a ‘technical details’ report for diagnostics.</p>
</section>
<section id="todos">
<h2>TODOs<a class="headerlink" href="#todos" title="Link to this heading">¶</a></h2>
<p>Syntax highlighting via Pygments?</p>
<p>Launch at any chapter via query param.  (Front-matter is ‘chapter 0’.)
The History API for browsers might make a nice addition, to allow you
to bookmark a particular chapter of the tutorial.</p>
<p>Challenges for the learner / alternative development approaches: GS
notes/asks: <em>If I wanted to show an alternative way to code something
in the tutorial then I wonder if I could make a branch and have that
somehow presented in the tutorial as an alternative to the main-line
of the tutorial? I wouldn’t want to do this much because I think it
would make the tutorial very untidy and hard to navigate.</em></p>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../webapp/user/index.html">Using the Pytch web app</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../vm/user/index.html">Writing Pytch programs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../about.html">About Pytch</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../developer.html">Developer documentation</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../developer/development-setup.html">Development setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/design-overview.html">Design overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../vm/developer/index.html">VM</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../webapp/developer/index.html">Webapp</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../medialib/developer/index.html">Media library</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/index.html">Website</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Tools</a><ul class="current">
<li class="toctree-l3 current"><a class="reference internal" href="../index.html#tutorial-compiler-and-related-tools">Tutorial compiler and related tools</a></li>
<li class="toctree-l3"><a class="reference internal" href="../index.html#assembly-of-website-bundle">Assembly of website bundle</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../source-build.html">Source and build information</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../releases/changelog.html">Changelog</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../legal/index.html">Legal information</a></li>
</ul>
<div class="docs-home-link"><hr>
  <ul>
    <li>
      <a href="../../index.html">Pytch help home</a>
    <li>
  </ul>
</div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
  </body>
</html>